package ro.romanescu.useradmin;

import java.net.URL;

import java.util.List;


/**
 * Exposes user management functionality interface, common operations.
 * Every user management library must implement the functionality exposed 
 * through this interface (for example oracle/ms sql server/ldap backened
 * user administration modules).
 */
public interface UserAdminModuleInterface
{
  /**
   * Return description for specific module implementation (for example:
   * "User administration module with LDAP back-end".
   * @return Description of the module functionality/implementation.
   */
  String getDescription();
  
  
  /**
   * Configure the library passing the configuration URL.
   * @param configurationFile Path to the configuration file
   */
  void configure( URL configurationFile ) throws UserAdminException;
  
  
  /**
   * List all the rights available within framework.
   * @param currentUser Currently logged user to verify its privilege to execute this operation 
   * @return List of rights
   * @throws UserAdminException Exception doing the specified operation
   */
  List<Class> rightList( IUser currentUser ) throws UserAdminException;

  
  /**
   * Retrive the list of roles which have assigned the specified right.
   * @param right Right to check roles for
   * @param currentUser Currently logged user to verify its privilege to execute this operation 
   * @return List of roles
   * @throws UserAdminException
   */
  List<IRole> rightGetAsigneeRoles( Class right, IUser currentUser ) throws UserAdminException;

  /**
   * Create new role.
   * @param role Role to be added
   * @param currentUser Currently logged user to verify its privilege to execute this operation
   * @return Role inserted in database
   * @throws UserAdminException Exception doing the specified operation
   */
  IRole roleCreate( IRole role, IUser currentUser ) throws UserAdminException;


  /**
   * Remove an assigned role from ADM_ROLES table. This method also removes all the
   * logical associations with users and rights.
   * @param role Role to be removed
   * @return true if operation was successful
   * @throws UserAdminException Exception doing the specified operation
   */
  void roleRemove( IRole role, IUser currentUser ) throws UserAdminException;


  void roleUpdate( IRole role, IUser currentUser ) throws UserAdminException;


  /**
   * List all the roles available within database.
   * @return List of roles
   * @throws UserAdminException Exception doing the specified operation
   */
  List<IRole> roleList( IUser currentUser ) throws UserAdminException;


  List<IUser> roleGetAsigneeUser( IRole role, IUser currentUser ) throws UserAdminException;


  /**
   * Assign new right to an role.
   * @param role Name of the role
   * @param right Name of the right
   * @param currentUser Record author - curent user
   * @return true if operation was successful
   * @throws UserAdminException Exception doing the specified operation
   */
  void roleAddRight( IRole role, IRight right, IUser currentUser ) throws UserAdminException;


  /**
   * Remove an right from a role.
   * @param role Name of the role
   * @param right Name of the right
   * @param currentUser Current user
   * @return true if operation was successful
   * @throws UserAdminException Exception doing the specified operation
   */
  void roleRemoveRight( IRole role , IRight right, IUser currentUser ) throws UserAdminException;


  /**
   * Retrieve the list of rights associated with a role.
   * @param role Name of the role
   * @return List of rights
   * @throws UserAdminException Exception doing the specified operation
   */
  List<IRight> roleGetRights( IRole role, IUser currentUser ) throws UserAdminException;


  /**
   * Insert new user into ADM_USERS table.
   * @param user User
   * @return true if operation was successful
   * @throws UserAdminException Exception doing the specified operation
   */
  void userCreate( IUser user, IUser currentUser ) throws UserAdminException;

  

  /**
   * Remove user from ADM_USERS and update ADM_USERS_ROLES.
   * @param user User
   * @return true if operation was successful
   * @throws UserAdminException Exception doing the specified operation
   */
  void userRemove( IUser user, IUser currentUser ) throws UserAdminException;


  void userUpdate( IUser user, IUser currentUser ) throws UserAdminException;
  

  /**
   * Retrieve the list of available users.
   * @return List of users
   * @throws UserAdminException Exception doing the specified operation
   */
  List<IUser> userList( IUser currentUser ) throws UserAdminException;


  /**
   * Find an user in database.
   * @return User or null if no user found
   * @throws UserAdminException Exception doing the specified operation
   */
  List<IUser> userFind( String searchString, IUser currentUser ) throws UserAdminException;


  /**
   * Add role to user.
   * @param user Name of the user
   * @param role Name of the role
   * @param currentUser Record author
   * @return true if operation was successful
   * @throws UserAdminException Exception doing the specified operation
   */
  void userAddRole( IUser user, IRole role, IUser currentUser ) throws UserAdminException;


  /**
   * Remove role from an user.
   * @param user
   * @param role
   * @return true if operation was successful
   * @throws UserAdminException Exception doing the specified operation
   */
  void userRemoveRole( IUser user, IRole role, IUser currentUser ) throws UserAdminException;


  /**
   * Get roles assigned to an user.
   * @param user User name
   * @return true if operation was successful
   * @throws UserAdminException Exception doing the specified operation
   */
  List<IRole> userGetRoles( IUser user, IUser currentUser ) throws UserAdminException;
  

  void userAddAttribute( IUser user, IUserAttribute attribute ) throws UserAdminException;
  
  void userRemoveAttribute( IUser user, IUserAttribute attribute ) throws UserAdminException; 
  
  List<IUserAttribute> userGetAttributes( IUser user, IUser currentUser) throws UserAdminException;

  void attributeCreate( IUserAttribute attribute, IUser currentUser ) throws UserAdminException;
  
  void attributeRemove( IUserAttribute attribute, IUser currentUser ) throws UserAdminException;

  void attributeUpdate( IUserAttribute attribute, IUser currentUser ) throws UserAdminException;
}
